This is just 1 way to host an Rmd document. There are other options. This is just intended to show how to do it with GitHub pages, it is not claiming to GitHub pages to be the best route for all cases.
index.htmlindex.html file into your GitHub repo
https://<your-username>.github.io/<your-repo-name/
AdamSpannbauerhosting-Rmds-with-GitHub-PagesEmbed other websites with knitr::include_url()! Shiny’s
an example option where you might have work to show off.
knitr::include_url("https://spannbaueradam.shinyapps.io/sql-racer/", height = "512px")Using {r out.width="100%", echo=FALSE} will set the
embed to 100% of its container’s width and hide the code that created
it. Eg, the you don’t see the embed code for the below example because
of echo=FALSE.
This embedded site has some starter info on using an
.ipynb for a site instead of an Rmd.
knitr::include_url()
https://public.tableau.com/views; if it mentions
user it will fail (this bullet will prolly fall out of
date)?:showVizHome=no&:embed=true right after the dashboard
name
https://public.tableau.com/views/recreate-test-f23/Dashboard1?:language=en-US&:display_count=n&:origin=viz_share_linkhttps://public.tableau.com/views/recreate-test-f23/Dashboard1?:showVizHome=no&:embed=trueThe below code is what creates the embedded view. If you don’t want
the code visible use echo=FALSE (that’s what made the
second embedded view here).
Note: This dashboard wasn’t designed to be so cramped. If it’s for an embedded portfolio piece, take some time to readjust things to work nicely.
The above was created with:
<iframe src="https://public.tableau.com/views/recreate-test-f23/Dashboard1?:showVizHome=no&:embed=true" width="100%" height="400px" data-external="1"></iframe>I cover some things you can do here, but Rmd is a very flexible thing! Pretty much anything you can do in R Markdown could be applied here. See the below online free resources for a very complete overview of what can be done:
A lot of what’s covered below deals with the “YAML front matter” that appears at the beginning of an .Rmd file.
The YAML used for this document is:
---
title: "Hosting Rmds with GitHub Pages"
author: "Adam Spannbauer"
date: "2023-12-04"
output:
html_document:
theme: flatly
toc: true
toc_depth: 2
toc_float: true
includes:
in_header: "favicon.html"
---All the contents of the the YAML are either self-explanatory (message
me if not!) or they’re discussed below. The exception is the usage of
Sys.Date() in the date: field; this will tell
the .Rmd file to look up today’s date when you click the knit button (ie
the date will serve as a “last updated” date).
Adding a theme is easy to do and can make documents look snazzy and professional.
Use the below YAML to tell your .Rmd what theme to use.
output:
html_document:
theme: flatlyThe options you can say other than flatly used above
are: cerulean, cosmo, cyborg, darkly, flatly, journal, lumen, paper,
readable, sandstone, simplex, slate, spacelab, superhero, united, yeti.
So many!!!
If you’re already in the know about CSS, it’s worth noting that you can apply you own style sheet to an Rmd file. See the official R Markdown Cookbook here.
This can be a great option if you really want to work towards unique consistent branding.
Again, a table of contents is just a little piece of YAML away. Below is what this doc uses:
output:
html_document:
toc: true
toc_depth: 2
toc_float: truetoc: true - turn on the table of contentstoc_depth: 2 - the table of contents should include
both first and second level headers (ie sections and sub-sections, not
sub-sub-sections etc)toc_float: true - the table of contents should always
appear on the side. Set to false and the table of contents
will be stuck to the top of the page (ie when users scroll down it will
scroll off the top of the page)See this section from R Markdown: The Definitive Guide for more options for the table of contents!
A little icon in the tab of your web browser can go a surprisingly long way in making a site look more professional. This little icon in the browser tab is known as a “favicon”. To add one, I’ve included the below in my YAML:
output:
html_document:
includes:
in_header: "favicon.html", and then I have this
small html file saved as favicon.html in the same
folder as my .Rmd file. To change the icon from the little emoji R,
you’d change the link to an image you’d like to be a favicon. They are
intended to be small images, so there’s a chance you don’t use this
feature perfectly as intended by web browsers.
library(ggplot2)
library(plotly)
library(dplyr)Part of the fun of being on the web instead of in a Word or PDF doc is that you can use interactive things in your Rmd!
For example here’s a plot made with ggplot2 and then
rendered with plotly to add some nice interactivity.
p <- ggplot(mtcars, aes(x = wt, y = mpg)) +
geom_point() +
labs(
x = "Car weight in 1000s of lbs",
y = "MPG"
)
ggplotly(p)You can also use plotly directly to do some pretty cool
things.
Data viz note: Is this the best way to show this data? Prolly not, as always double check the story you want to tell and focus on that. But animations are fun to play with!
keep_cities <- c(
"Arlington", "Austin", "Dallas",
"El Paso", "Fort Worth", "Houston",
"Lubbock", "San Antonio"
)
annual_txhousing <- txhousing %>%
filter(city %in% keep_cities) %>%
group_by(city, year) %>%
summarise(
sales = sum(sales),
volume = sum(volume)
)
plot_ly(
annual_txhousing,
x = ~ log(sales),
y = ~ log(volume),
color = ~city,
frame = ~year,
type = "scatter",
mode = "markers"
) %>%
layout(
xaxis = list(title = "log(Number of Sales)"),
yaxis = list(title = "log(Total value of Sales)")
)